Testing & Troubleshooting

How to test the bot manually and troubleshoot common issues

Overview

Before relying on the automated schedule, it’s important to test your bot configuration. This guide covers manual testing and troubleshooting common problems.

Manual Testing with workflow_dispatch

The workflow includes workflow_dispatch which allows manual execution:

.github/workflows/main.yml

on:
  schedule:
    - cron: '0 15 * * 1-5'
    - cron: '0 21 * * 1-5'
  workflow_dispatch: # Permite ejecutarlo manualmente para probar

Running Manually on GitHub

1. Navigate to Actions

   1. Go to your GitHub repository
   2. Click the Actions tab at the top
   3. You’ll see a list of workflows on the left sidebar
2. Select Workflow

   Click on Registro WhatsApp Automático (or your workflow name) in the left sidebar.

3. Run Workflow

   1. Click the Run workflow dropdown button (top right)
   2. Select the branch (usually main or master)
   3. Click the green Run workflow button

   The workflow will start immediately and typically completes in 10-20 seconds.

4. View Results

   1. Wait a few seconds for the run to appear
   2. Click on the workflow run
   3. Click on the run-bot job
   4. Expand the Execute Script step
   5. Check the output for status and response

Expected Output

A successful run shows:

Run python bot.py
Status: 200, Response: {"sent":"true","message":"ok","id":"..."}

The message sent depends on the current UTC time. If you run it before 18:00 UTC, it sends the “Entrada” message. After 18:00 UTC, it sends “Salida”.

Local Testing

For faster iteration, test the bot locally before pushing to GitHub:

Setup Local Environment

1. Clone Repository

   git clone https://github.com/your-username/your-repo.git
   cd your-repo
   
2. Install Dependencies

   pip install requests
   
3. Set Environment Variables

   Create a .env file or export variables:

   Linux/Mac

   export INSTANCE_ID="your_instance_id"
   export TOKEN="your_token"
   export GROUP_ID="your_group_id"
   

   Windows (CMD)

   set INSTANCE_ID=your_instance_id
   set TOKEN=your_token
   set GROUP_ID=your_group_id
   

   Windows (PowerShell)

   $env:INSTANCE_ID="your_instance_id"
   $env:TOKEN="your_token"
   $env:GROUP_ID="your_group_id"
   

   Never commit your actual credentials to the repository. Add .env to your .gitignore file.

4. Run the Script

   python bot.py
   

   You should see output like:

   Status: 200, Response: {"sent":"true","message":"ok"}
   

Testing Different Time Conditions

Since the message depends on UTC hour, you can temporarily modify the logic for testing:

bot.py

# Original code
ahora_hora = datetime.datetime.utcnow().hour
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

# For testing - force "Entrada" message
ahora_hora = 10  # Simulate morning
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

# For testing - force "Salida" message  
ahora_hora = 20  # Simulate evening
mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"

Remember to revert these changes before committing to GitHub.

Troubleshooting Common Issues

Issue: 401 Unauthorized

Symptoms:

Status: 401, Response: {"error":"Unauthorized"}

Causes and Solutions:

1. Check TOKEN Secret

   1. Go to repository Settings > Secrets and variables > Actions
   2. Verify TOKEN secret exists and is not expired
   3. Update the token if needed from your UltraMsg dashboard
2. Verify Instance ID

   The INSTANCE_ID must match your active UltraMsg instance:

   1. Log in to UltraMsg dashboard
   2. Check your instance ID (format: instance12345)
   3. Update the INSTANCE_ID secret if it’s incorrect

Issue: 404 Not Found

Symptoms:

Status: 404, Response: {"error":"Chat not found"}

Causes and Solutions:

1. Verify Group ID Format

   WhatsApp group IDs must follow the format:

   [e-mail]
   

   • Must include country code (e.g., 52 for Mexico)
   • Must end with @g.us for groups
   • Must include the group unique identifier after the dash
2. Get Correct Group ID

   To find your group ID:

   1. Send a test message to the group through UltraMsg dashboard
   2. Use the UltraMsg API to list chats:

   curl "https://api.ultramsg.com/{instance_id}/chats?token={token}"
   

   3. Find your group in the response and copy its ID

Issue: Workflow Not Running on Schedule

Symptoms:

• Workflow doesn’t execute at scheduled times
• No runs appear in Actions tab

Causes and Solutions:

1. Check Workflow File Location

   Ensure the workflow file is at:

   .github/workflows/main.yml
   

   The .github/workflows/ directory must be at the root of your repository.

2. Verify YAML Syntax

   Invalid YAML prevents the workflow from running:

   1. Go to Actions tab
   2. Look for syntax error messages
   3. Use a YAML validator to check your file

   GitHub shows a red X next to the file in the repository if there’s a syntax error.

3. Check Repository Activity

   GitHub may disable scheduled workflows for inactive repositories:

   1. Make a commit to re-enable workflows
   2. Ensure the repository isn’t archived
   3. Verify workflows are enabled in Settings > Actions > General
4. Understand Schedule Delays

   GitHub Actions scheduled workflows may have delays:

   • Typically run within 5-15 minutes of scheduled time
   • During high load, delays can be longer
   • Not guaranteed to be exact

   For critical time-sensitive notifications, consider using an external service with webhooks.

Issue: Wrong Message Sent

Symptoms:

• “Salida” message sent in the morning
• “Entrada” message sent in the evening

Causes and Solutions:

1. Check Time Threshold Logic

   The condition at bot.py:13 determines the message:

   ahora_hora = datetime.datetime.utcnow().hour
   mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"
   

   • If UTC hour < 18 → “Entrada”
   • If UTC hour ≥ 18 → “Salida”
2. Verify Schedule Times

   Check your cron schedule matches your timezone:

   schedule:
     - cron: '0 15 * * 1-5'  # Should be morning in your timezone
     - cron: '0 21 * * 1-5'  # Should be evening in your timezone
   

   For CST (UTC-6):

   • 15:00 UTC = 9:00 AM CST (before 18:00 UTC ✓)
   • 21:00 UTC = 3:00 PM CST (after 18:00 UTC ✓)
3. Adjust Threshold if Needed

   If your afternoon run is before 18:00 UTC, adjust the threshold:

   # If your afternoon run is at 17:00 UTC (e.g., 9:00 AM PST)
   mensaje = "Name \n Entrada \n 9:00 AM" if ahora_hora < 12 else "Name\n Salida\n 3:00 PM"
   

Issue: Environment Variables Not Found

Symptoms:

AttributeError: 'NoneType' object has no attribute '...'

Causes and Solutions:

1. Verify Secret Names

   In .github/workflows/main.yml, check the environment variable mapping:

   env:
     INSTANCE_ID: ${{ secrets.INSTANCE_ID }}
     TOKEN: ${{ secrets.TOKEN }}
     GROUP_ID: ${{ secrets.GROUP_ID }}
   

   Secret names are case-sensitive and must match exactly.

2. Confirm Secrets Exist

   1. Go to Settings > Secrets and variables > Actions
   2. Verify all three secrets are listed
   3. Re-add any missing secrets
3. Check for Typos in bot.py

   Ensure environment variable names match:

   instance_id = os.getenv('INSTANCE_ID')  # Must match workflow
   token = os.getenv('TOKEN')
   group_id = os.getenv('GROUP_ID')
   

Debugging Tips

Add Debug Output

Add print statements to understand what’s happening:

import requests
import os
import datetime

def enviar_registro():
    instance_id = os.getenv('INSTANCE_ID')
    token = os.getenv('TOKEN')
    group_id = os.getenv('GROUP_ID')
    
    # Debug output
    print(f"Instance ID: {instance_id[:8]}...")
    print(f"Group ID: {group_id}")
    
    ahora_hora = datetime.datetime.utcnow().hour
    print(f"Current UTC hour: {ahora_hora}")
    
    mensaje = "Aldo Tolentino \n Entrada \n 9:00 AM" if ahora_hora < 18 else "Aldo Tolentino\n Salida\n 3:00 PM"
    print(f"Message: {mensaje}")
    
    url = f"https://api.ultramsg.com/{instance_id}/messages/chat"
    payload = {
        "token": token,
        "to": group_id,
        "body": mensaje
    }
    headers = {'content-type': 'application/x-www-form-urlencoded'}
    
    r = requests.post(url, data=payload, headers=headers)
    print(f"Status: {r.status_code}, Response: {r.text}")

Never print full tokens or sensitive credentials, even in GitHub Actions logs. Use truncation like token[:8]... if needed.

Test UltraMsg API Directly

Test your credentials with curl:

curl -X POST "https://api.ultramsg.com/{instance_id}/messages/chat" \
  -d "token={token}" \
  -d "to={group_id}" \
  -d "body=Test message from curl"

If this works but the bot doesn’t, the issue is in your Python code.

Check GitHub Actions Logs

Detailed logs are available for each step:

1. Go to Actions tab
2. Click on a workflow run
3. Click on the run-bot job
4. Each step can be expanded to see full output
5. Look for error messages in red

Getting Help

If you’re still having issues:

1. Check the UltraMsg API documentation
2. Verify your UltraMsg instance is active and connected
3. Review the GitHub Actions logs for error details
4. Test locally with debug output enabled

Keep your UltraMsg instance connected to WhatsApp Web. If it disconnects, you’ll need to scan the QR code again in the UltraMsg dashboard.